Scripting
文档
更新日志
隐私
文档
更新日志
隐私
简体中文

Request 和 RequestInit

Request 类表示一次 HTTP 请求的完整配置。 它可作为 fetch() 方法的参数使用，也可用于克隆、修改或重试请求。

在 Scripting 中，Request 的行为与浏览器 Fetch API 中的同名接口一致，但额外支持了原生扩展功能，包括：

  • 支持二进制 Data 类型作为请求体
  • 支持自定义重定向处理
  • 支持请求超时、取消、与调试标签
  • 支持允许不安全请求（HTTP 请求）

类定义

1class Request {
2  url: string
3  method: string
4  headers: Headers
5  body?: Data | FormData | string | ArrayBuffer
6  allowInsecureRequest?: boolean
7  handleRedirect?: (newRequest: RedirectRequest) => Promise<RedirectRequest | null>
8  shouldAllowRedirect?: (newRequest: Request) => Promise<boolean> // 已废弃
9  timeout?: DurationInSeconds
10  signal?: AbortSignal
11  cancelToken?: CancelToken // 已废弃
12  debugLabel?: string
13
14  constructor(input: string | Request, init?: RequestInit)
15  clone(): Request
16}

构造函数

new Request(input: string | Request, init?: RequestInit)

创建一个新的 Request 实例。 可通过字符串 URL 或现有的 Request 对象来构造。

参数

参数 类型 说明
input string Request
init RequestInit 可选的初始化参数，用于配置请求的行为（见下文）。

属性

属性名 类型 说明
url string 请求的完整 URL。
method string 请求方法（默认 "GET"）。
headers Headers 请求头部对象，可通过 .get()、.set()、.append() 等方法操作。
body Data | FormData | string | ArrayBuffer | undefined 请求体，仅用于非 GET 或 HEAD 请求。
allowInsecureRequest boolean 是否允许使用 HTTP 明文请求（默认 false）。
handleRedirect (newRequest: RedirectRequest) => Promise<RedirectRequest | null> 自定义重定向逻辑；返回 null 表示阻止重定向。
shouldAllowRedirect (newRequest: Request) => Promise<boolean> 已废弃。旧版重定向控制回调。
timeout number 请求超时时间（单位：秒）。超时会自动中止请求。
signal AbortSignal 用于中止请求的信号，由 AbortController 创建。
cancelToken CancelToken 已废弃。旧版取消机制，请改用 signal。
debugLabel string 调试标签，会在日志面板中显示以方便追踪。

方法

clone(): Request

创建并返回当前请求对象的副本。 克隆后的对象可安全修改其属性（如 headers、body）而不影响原始请求。

示例

1const req1 = new Request("https://api.example.com/user", {
2  method: "POST",
3  headers: { "Content-Type": "application/json" },
4  body: JSON.stringify({ name: "Alice" })
5})
6
7const req2 = req1.clone()
8console.log(req2.method) // "POST"

使用示例

示例 1：创建一个简单的 Request 对象

1const request = new Request("https://api.example.com/data", {
2  method: "GET",
3  headers: {
4    "Accept": "application/json",
5  },
6  debugLabel: "Fetch User Data"
7})
8
9const response = await fetch(request)
10const result = await response.json()
11console.log(result)

示例 2：带请求体的 POST 请求

1const request = new Request("https://api.example.com/upload", {
2  method: "POST",
3  headers: { "Content-Type": "application/json" },
4  body: JSON.stringify({ fileId: "abc123" }),
5  timeout: 15,
6})
7
8const response = await fetch(request)
9console.log(await response.text())

示例 3：克隆并修改请求

1const base = new Request("https://api.example.com/posts", {
2  method: "POST",
3  headers: { "Content-Type": "application/json" },
4})
5
6const cloned = base.clone()
7cloned.headers.set("Authorization", "Bearer token-123")
8cloned.debugLabel = "Authorized Upload"
9
10await fetch(cloned)

RequestInit 类型

RequestInit 是一个用于配置请求参数的对象类型，常用于 fetch() 或 Request 构造函数中。 它与浏览器的标准 Fetch API 相同，但 Scripting 扩展了若干字段。

类型定义

1type RequestInit = {
2  method?: string
3  headers?: HeadersInit
4  body?: Data | FormData | string | ArrayBuffer
5  allowInsecureRequest?: boolean
6  handleRedirect?: (newRequest: RedirectRequest) => Promise<RedirectRequest | null>
7  shouldAllowRedirect?: (newRequest: Request) => Promise<boolean> // 已废弃
8  timeout?: DurationInSeconds
9  signal?: AbortSignal
10  cancelToken?: CancelToken // 已废弃
11  debugLabel?: string
12}

字段说明

字段名 类型 说明
method string HTTP 方法，如 "GET", "POST", "PUT", "DELETE"，默认 "GET"。
headers HeadersInit 请求头部信息，可以是：Headers 对象、普通对象 {key: value}、或 [key, value][] 数组。
body Data | FormData | string | ArrayBuffer 请求体，仅在非 GET / HEAD 请求中使用。
allowInsecureRequest boolean 是否允许发送 HTTP 请求。默认 false。
handleRedirect (newRequest: RedirectRequest) => Promise<RedirectRequest | null> 自定义重定向回调。返回新的请求对象以继续，返回 null 以阻止跳转。
shouldAllowRedirect (newRequest: Request) => Promise<boolean> 已废弃。旧的布尔型重定向控制回调。
timeout number 请求超时时间（秒），超时后会自动中止请求。
signal AbortSignal 中止信号，可由 AbortController 触发，用于主动取消请求。
cancelToken CancelToken 已废弃。旧版取消机制，请使用 signal 替代。
debugLabel string 调试标签，在日志面板中显示，用于标识请求。

与 fetch() 的关系

RequestInit 是 fetch() 的第二个参数，用于定义请求配置：

1const response = await fetch("https://example.com/data", {
2  method: "POST",
3  headers: { "Content-Type": "application/json" },
4  body: JSON.stringify({ id: 123 }),
5  timeout: 10,
6  debugLabel: "Upload JSON",
7})

与其他类的关系

类名 用途
Headers 管理请求头部的集合，可与 headers 字段一起使用。
Data 表示二进制数据，可作为请求体（body）上传文件或原始字节数据。
FormData 用于构造 multipart/form-data 表单请求。
AbortController / AbortSignal 用于在请求过程中主动取消网络操作。
CancelToken 旧版取消机制，仅为兼容保留。
RedirectRequest 当发生重定向时传入 handleRedirect 回调的参数，包含新请求的详细信息。

示例

示例 1：使用自定义重定向回调

1const response = await fetch("https://example.com/start", {
2  handleRedirect: async (newRequest) => {
3    console.log("收到重定向:", newRequest.url)
4    if (newRequest.url.includes("blocked")) return null
5    return newRequest
6  },
7})

示例 2：允许不安全请求

1const response = await fetch("http://insecure.example.com/data", {
2  allowInsecureRequest: true,
3})
4console.log(await response.text())

示例 3：带调试标签的请求

1await fetch("https://example.com/api/ping", {
2  debugLabel: "Ping Request",
3})
4// 调试面板中将显示标签 “Ping Request”

以下是 handleRedirect 回调中 RedirectRequest 接口的中文说明文档，可直接插入至 Request 类文档的相关部分，用于解释自定义重定向逻辑的参数结构和用法。

RedirectRequest 接口说明

当请求发生 重定向 (Redirect) 时，若在 Request 或 RequestInit 中设置了 handleRedirect 回调函数，系统会在跳转前调用该回调。 handleRedirect 的参数类型为 RedirectRequest，用于描述即将执行的重定向请求的完整信息。 你可以在回调中检查该对象的属性，并决定是否允许继续重定向，或修改请求后再继续。

接口定义

1interface RedirectRequest {
2  method: string
3  url: string
4  headers: Record<string, string>
5  cookies: Cookie[]
6  body?: Data
7  timeout?: number
8}

字段说明

字段 类型 说明
method string 即将执行的重定向请求方法（例如 "GET"、"POST"）。
url string 重定向目标的完整 URL。
headers Record<string, string> 该重定向请求的 HTTP 头部信息。你可以根据需要修改或记录这些头部。
cookies Cookie[] 当前请求中携带的 Cookie 列表，类型与 Response.cookies 一致。
body Data（可选） 若为非 GET 请求，则包含请求体数据（例如表单或二进制数据）。
timeout number（可选） 请求的超时时间（单位：秒）。

使用场景

通过 handleRedirect 回调，你可以：

  • 检查重定向目标地址是否安全或符合业务逻辑。
  • 修改重定向请求（如添加自定义头部、调整方法或携带 Token）。
  • 阻止不必要或可疑的重定向。

当回调返回：

  • 一个 RedirectRequest 对象 → 表示允许重定向，并使用你返回的对象继续请求。
  • null → 表示阻止此次重定向，fetch() 将在当前响应结束。

示例：拦截与控制重定向请求

1const response = await fetch("https://example.com/start", {
2  handleRedirect: async (redirect) => {
3    console.log("即将重定向至:", redirect.url)
4
5    // 如果跳转到外部域名，则阻止
6    if (!redirect.url.startsWith("https://example.com")) {
7      console.warn("阻止外部重定向:", redirect.url)
8      return null
9    }
10
11    // 向重定向请求添加授权头
12    redirect.headers["Authorization"] = "Bearer my-token"
13    return redirect
14  },
15})

示例：修改重定向请求方法与体

1const response = await fetch("https://api.example.com/login", {
2  handleRedirect: async (redirect) => {
3    // 如果重定向目标为 POST 接口，则保持原始请求体
4    if (redirect.url.includes("/finalize")) {
5      redirect.method = "POST"
6      redirect.body = Data.fromRawString("action=confirm", "utf-8")
7    }
8    return redirect
9  },
10})

注意事项

  • 若未设置 handleRedirect，所有重定向将默认自动执行。
  • 若设置了 handleRedirect 且返回 null，fetch() 不会继续跳转。
  • 该机制不会自动携带 Cookie，需要手动在 RedirectRequest.cookies 中读取并决定是否传递。
  • 修改 RedirectRequest 返回后，系统会基于修改后的内容重新发起请求。

小结

Request 与 RequestInit 是 Scripting 网络请求系统的核心基础：

  • Request 封装了完整的 HTTP 请求对象，可复用、克隆与传递。
  • RequestInit 定义请求参数，提供灵活的初始化方式。
  • 二者与 fetch()、Response、Headers、Data、FormData 等类型紧密配合。
大纲